Skip Headers

Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next

# 172 UTL_MAIL

The `UTL_MAIL` package is a utility for managing email which includes commonly used email features, such as attachments, CC, BCC, and return receipt.

This chapter contains the following topics:

- Using UTL_MAIL

  - Security Model

  - Operational Notes

- Summary of UTL_MAIL Subprograms

## Using UTL_MAIL

- Security Model

- Operational Notes

### Security Model

`UTL_MAIL` is not installed by default because of the `SMTP_OUT_SERVER` configuration requirement and the security exposure this involves. In installing `UTL_MAIL`, you should take steps to prevent the port defined by `SMTP_OUT_SERVER` being swamped by data transmissions`.`

### Operational Notes

You must both install `UTL_MAIL` and define the `SMTP_OUT_SERVER.`

- To install UTL_MAIL:

    sqlplus sys/<pwd>
    SQL> @$ORACLE_HOME/rdbms/admin/utlmail.sql
    SQL> @$ORACLE_HOME/rdbms/admin/prvtmail.plb

- You define the `SMTP_OUT_SERVER` parameter in the `init`.`ora` `rdbms` initialization file. However, if `SMTP_OUT_SERVER` is not defined, this invokes a default of `DB_DOMAIN` which is guaranteed to be defined to perform appropriately.

## Summary of UTL_MAIL Subprograms

Table 172-1 UTL_MAIL Package Subprograms

Subprogram | Description
--- | ---
SEND Procedure | Packages an email message into the appropriate format, locates SMTP information, and delivers the message to the SMTP server for forwarding to the recipients
SEND_ATTACH_RAW Procedure | Represents the `SEND` Procedure overloaded for `RAW` attachments
SEND_ATTACH_VARCHAR2 Procedure | Represents the `SEND` Procedure overloaded for `VARCHAR2` attachments

### SEND Procedure

This procedure packages an email message into the appropriate format, locates SMTP information, and delivers the message to the SMTP server for forwarding to the recipients. It hides the SMTP API and exposes a one-line email facility for ease of use.

Syntax

    UTL_MAIL.SEND (
       sender      IN    VARCHAR2 CHARACTER SET ANY_CS,
       recipients  IN    VARCHAR2 CHARACTER SET ANY_CS,
       cc          IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       bcc         IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       subject     IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       message     IN    VARCHAR2 CHARACTER SET ANY_CS,
       mime_type   IN    VARCHAR2 DEFAULT 'text/plain; charset=us-ascii',
       priority    IN    PLS_INTEGER DEFAULT NULL);

Parameters

Table 172-2 SEND Procedure Parameters

Parameter | Description
--- | ---
`sender` | The email address of the sender.
`recipients` | The email addresses of the recipient(s), separated by commas.
`cc` | The email addresses of the CC recipient(s), separated by commas, default is `NULL`
`bcc` | The email addresses of the BCC recipient(s), separated by commas, default is `NULL`
`subject` | A string to be included as email subject string, default is `NULL`
`message` | A text message body.
`mime_type` | The mime type of the message, default is 'text/plain; charset=us-ascii'
`priority` | The message priority, default is `NULL.`

### SEND_ATTACH_RAW Procedure

This procedure is the `SEND` Procedure overloaded for `RAW` attachments.

Syntax

    UTL_MAIL.SEND_ATTACH_RAW (
       sender           IN    VARCHAR2 CHARACTER SET ANY_CS,
       recipients       IN    VARCHAR2 CHARACTER SET ANY_CS,
       cc               IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       bcc              IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       subject          IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       message          IN    VARCHAR2 CHARACTER SET ANY_CS,
       mime_type        IN    VARCHAR2 DEFAULT 'text/plain; charset=us-ascii',
       priority         IN    PLS_INTEGER DEFAULT NULL
       attachment       IN    RAW,
       att_inline   IN    BOOLEAN DEFAULT TRUE,
       att_mime_type    IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT
                              'application/octet',
       att_filename     IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 172-3 SEND_ATTACH_RAW Procedure Parameters

Parameter | Description
--- | ---
`sender` | The email address of the sender.
`recipients` | The email addresses of the recipient(s), separated by commas.
`cc` | The email addresses of the CC recipient(s), separated by commas, default is `NULL.`
`bcc` | The email addresses of the BCC recipient(s), separated by commas, default is `NULL.`
`subject` | A string to be included as email subject string, default is `NULL.`
`message` | A text message body.
`mime_type` | The mime type of the message, default is 'text/plain; charset=us-ascii'.
`priority` | The message priority, the default is `NULL.`
`attachment` | A `RAW` attachment.
`att_inline` | Specifies whether the attachment is viewable inline with the message body, default is `TRUE`.
`att_mime_type` | The mime type of the attachment, default is 'application/octet'.
`att_filename` | The string specifying a filename containing the attachment, default is `NULL.`

### SEND_ATTACH_VARCHAR2 Procedure

This procedure is the `SEND` Procedure overloaded for `VARCHAR2` attachments.

Syntax

    UTL_MAIL.SEND_ATTACH_VARCHAR2 (
       sender            IN    VARCHAR2 CHARACTER SET ANY_CS,
       recipients        IN    VARCHAR2 CHARACTER SET ANY_CS,
       cc                IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       bcc               IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       subject           IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT NULL,
       message           IN    VARCHAR2 CHARACTER SET ANY_CS,
       mime_type         IN    VARCHAR2 DEFAULT 'text/plain; charset=us-ascii',
       priority          IN    PLS_INTEGER DEFAULT NULL
       attachment        IN    RAW,
       att_inline        IN    BOOLEAN DEFAULT TRUE,
       att_mime_type     IN    VARCHAR2 CHARACTER SET ANY_CS DEFAULT
                              'application/octet',
       att_filename      IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 172-4 SEND_ATTACH_VARCHAR2 Procedure Parameters

Parameter | Description
--- | ---
`sender` | The email address of the sender.
`recipients` | The email addresses of the recipient(s), separated by commas.
`cc` | The email addresses of the CC recipient(s), separated by commas, default is `NULL`.
`bcc` | The email addresses of the BCC recipient(s), separated by commas, default is `NULL.`
`subject` | A string to be included as email subject string, default is `NULL.`
`message` | A text message body.
`mime_type` | The mime type of the message, default is 'text/plain; charset=us-ascii'.
`priority` | The message priority, the default is `NULL.`
`attachment` | A text attachment.
`att_inline` | Specifies whether the attachment is inline, default `TRUE`.
`att_mime_type` | The mime type of the attachment, default is 'text/plain; charset=us-ascii'.
`att_filename` | The string specifying a filename containing the attachment, default is `NULL`.